/**
 * @file SimpleCDBUS.h
 * @brief SimpleCDBUS Arduino库头文件
 * @details 为Arduino平台提供CDBUS协议的完整接口定义
 *          支持串口通信、数据包收发、地址过滤等功能
 * 
 * @author 修改团队：mastwet@Undefine Innovation
 * @date 2024
 * @copyright MIT License
 * 
 * @note 适用于Arduino UNO、Mega、ESP32等支持HardwareSerial的开发板
 * @note 使用示例：
 * @code
 * SimpleCDBUS bus;
 * bus.begin(&Serial, 0x01);  // 初始化，地址0x01
 * bus.send(0x02, data, len); // 向地址0x02发送数据
 * if (bus.available()) {
 *     uint8_t src;
 *     uint8_t buffer[64];
 *     uint8_t len = bus.read(&src, buffer, sizeof(buffer));
 * }
 * @endcode
 */

#ifndef SIMPLE_CDBUS_H
#define SIMPLE_CDBUS_H

#include <Arduino.h>
#include "cdbus.h"

/**
 * @class SimpleCDBUS
 * @brief SimpleCDBUS Arduino库主类
 * @details 提供CDBUS协议的完整功能封装，包括：
 *          - 串口通信初始化和管理
 *          - 数据包的发送和接收
 *          - 地址过滤和配置
 *          - 错误处理和状态查询
 */
class SimpleCDBUS {
private:
    HardwareSerial *_serial;    /**< 硬件串口指针 */
    uint8_t _address;           /**< 本设备CDBUS地址 */
    bool _initialized;          /**< 初始化标志 */
    
    /**
     * @brief CDBUS缓冲区
     * @details 为接收和发送数据提供缓冲区
     *          大小由CDBUS_MAX_FRAME_SIZE定义（通常为255字节）
     */
    uint8_t _rx_buffer[CDBUS_MAX_FRAME_SIZE];  /**< 接收缓冲区 */
    uint8_t _tx_buffer[CDBUS_MAX_FRAME_SIZE];  /**< 发送缓冲区 */
    
    /**
     * @brief CDBUS协议状态
     * @details 包含协议栈的所有状态信息：
     *          - 接收状态机状态
     *          - 当前帧缓冲区
     *          - 地址过滤器
     *          - 错误计数器
     */
    cdbus_t _cdbus;
    
public:
    /**
     * @brief 构造函数
     * @details 创建SimpleCDBUS对象实例
     *          初始化所有成员变量为默认值
     */
    SimpleCDBUS();
    
    /**
     * @name 初始化相关函数
     * @{
     */
    
    /**
     * @brief 初始化CDBUS库
     * @param serial 硬件串口指针（如&Serial、&Serial1等）
     * @param address 本设备的CDBUS地址（0-255）
     * @details 必须在调用其他函数前调用此函数
     */
    void begin(HardwareSerial *serial, uint8_t address);
    
    /**
     * @brief 关闭CDBUS库
     * @details 关闭串口通信并重置初始化状态
     */
    void end();
    
    /** @} */
    
    /**
     * @name 基本操作函数
     * @{
     */
    
    /**
     * @brief 发送数据包
     * @param dst 目标设备地址（0-255）
     * @param data 要发送的数据缓冲区
     * @param len 数据长度（字节数）
     * @details 构造CDBUS数据帧并通过串口发送
     *          自动添加CRC校验和帧头帧尾
     */
    void send(uint8_t dst, uint8_t *data, uint8_t len);
    
    /**
     * @brief 读取接收到的数据包
     * @param src 返回源设备地址（可选，传入NULL忽略）
     * @param buffer 接收数据缓冲区
     * @param max_len 缓冲区最大长度
     * @return 实际读取的数据长度（字节数），0表示无数据
     * @details 从接收缓冲区读取一个完整的数据包
     */
    uint8_t read(uint8_t *src, uint8_t *buffer, uint8_t max_len);
    
    /**
     * @brief 检查是否有数据包可读取
     * @return true表示有完整数据包可读取，false表示无数据
     */
    bool available();
    
    /** @} */
    
    /**
     * @name 配置函数
     * @{
     */
    
    /**
     * @brief 设置地址过滤器
     * @param filter 过滤模式（CDBUS_FILTER_*常量）
     * @details 设置接收过滤器，决定接收哪些地址的数据包
     */
    void setFilter(uint8_t filter);
    
    /**
     * @brief 设置串口波特率
     * @param baud 波特率值（如9600、19200、38400、57600、115200等）
     * @details 动态修改串口通信波特率
     */
    void setBaudRate(uint32_t baud);
    
    /** @} */
    
    /**
     * @name 状态查询函数
     * @{
     */
    
    /**
     * @brief 获取设备地址
     * @return 当前设置的CDBUS设备地址
     */
    uint8_t getAddress() { return _address; }
    
    /**
     * @brief 检查是否已初始化
     * @return true表示已初始化，false表示未初始化
     */
    bool isInitialized() { return _initialized; }
    
    /** @} */
    
    /**
     * @brief 更新状态
     * @details 处理串口接收的数据，更新协议状态机
     *          建议在loop()函数中定期调用
     */
    void update();
    
private:
    /**
     * @brief 初始化CDBUS协议栈
     * @details 内部函数，用于初始化CDBUS协议处理结构
     */
    void initializeCDBUS();
    
    /**
     * @brief 处理串口数据
     * @details 内部函数，从串口读取数据并送入协议栈处理
     */
    void processSerialData();
};

#endif // SIMPLE_CDBUS_H